home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / animutil / fastgfx / fg303b / manuals.arj / USER16.DOC < prev    next >
Text File  |  1993-10-02  |  8KB  |  198 lines
  1. Chapter 16
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Program Timing
  8. 300   Fastgraph User's Guide
  9.  
  10.  
  11. Overview
  12.  
  13.      It is occasionally necessary to delay a program's execution for a brief
  14. period, or to determine how long it takes to execute specific sections of a
  15. program.  Fastgraph includes routines to accomplish these tasks.  Some of
  16. these routines are said to be real-time, which means they are independent of
  17. a system's processor speed, while the speed of others is processor-specific.
  18. This chapter describes both classes of timing routines, all of which are
  19. independent of the other parts of Fastgraph.
  20.  
  21.  
  22. Real-Time Routines
  23.  
  24.      Real-time operations center around the BIOS time-of-day clock, which is
  25. nothing more than a counter that the system automatically increments 18.2
  26. times per second.  This number is often called the clock tick interrupt rate
  27. because an interrupt routine performs the incrementing.  In addition, each
  28. increment is usually called a clock tick.
  29.  
  30.      The Fastgraph routine fg_waitfor delays a program's execution by the
  31. number of clock ticks specified as its argument.  Because fg_waitfor uses
  32. clock ticks, the actual length of the delay is the same, regardless of the
  33. system's processor speed.  Even when Fastgraph's asynchronous sound routines
  34. quadruple the clock tick interrupt rate, Fastgraph compensates for this
  35. internally so fg_waitfor always works as though the actual rate were still
  36. 18.2 times per second.
  37.  
  38.      Example 16-1 displays a message every five seconds that states how long
  39. the program has been running.  The fg_waitfor routine produces the five-
  40. second delay by pausing 91 (18.2 times 5) clock ticks before the program
  41. displays each message.  The program returns to DOS when you press any key.
  42.  
  43.                                 Example 16-1.
  44.  
  45.              #include <fastgraf.h>
  46.              #include <stdio.h>
  47.              void main(void);
  48.  
  49.              void main()
  50.              {
  51.                 unsigned int seconds;
  52.                 unsigned char key, aux;
  53.  
  54.                 seconds = 0;
  55.  
  56.                 do {
  57.                    fg_waitfor(91);
  58.                    seconds += 5;
  59.                    printf("%u seconds have elapsed.\n",seconds);
  60.                    fg_intkey(&key,&aux);
  61.                 }
  62.                 while (key+aux == 0);
  63.              }
  64.  
  65.                                              Chapter 16:  Program Timing   301
  66.  
  67.      Another common application of the fg_waitfor routine is to slow down a
  68. loop that uses the fg_intkey routine to check for keystrokes.  In loops that
  69. do little else, we may call fg_intkey too rapidly without this delay, and it
  70. is then possible that the BIOS may not be able to store characters in its
  71. keyboard buffer fast enough.  A small delay, even one clock tick, often helps
  72. such "tight" loops.
  73.  
  74.      The fg_getclock routine provides an efficient way to measure time,
  75. especially differences in time.  This routine has no arguments and returns a
  76. 32-bit unsigned integer (as its function value) representing the number of
  77. clock ticks since midnight.  Example 16-2 demonstrates the fg_getclock
  78. routine.  In response to any keystroke (except Escape, which returns control
  79. to DOS), the program displays the number of clock ticks since midnight, and
  80. the number of ticks since the program started.
  81.  
  82.                                 Example 16-2.
  83.  
  84.       #include <fastgraf.h>
  85.       #include <stdio.h>
  86.       void main(void);
  87.  
  88.       #define ESC 27
  89.  
  90.       void main()
  91.       {
  92.          unsigned long start, ticks;
  93.          unsigned char key, aux;
  94.  
  95.          start = fg_getclock();
  96.  
  97.          do {
  98.             ticks = fg_getclock();
  99.             printf("%lu ticks since midnight.\n",ticks);
  100.             printf("%lu ticks since start of program.\n\n",ticks-start);
  101.             fg_getkey(&key,&aux);
  102.          }
  103.          while (key != ESC);
  104.       }
  105.  
  106.  
  107.  
  108. Routines Dependent on the System Speed
  109.  
  110.      The fg_waitfor routine described in the previous section is independent
  111. of the system's processor speed.  This means the actual length of its delay
  112. is the same on any system.  Another routine, fg_stall, is similar to
  113. fg_waitfor, but its delay is proportional to the processor speed.  Like
  114. fg_waitfor, fg_stall has a single integer argument that specifies the length
  115. of the delay.  However, instead of being expressed in clock ticks, fg_stall
  116. measures the delay in delay units.  The fg_stall routine treats the length as
  117. an unsigned quantity, so the maximum number of delay units we can specify is
  118. 65,535.  The following table lists the approximate number of delay units per
  119. clock tick on three typical systems.
  120. 302   Fastgraph User's Guide
  121.                       system       delay units
  122.                        type      per clock tick
  123.  
  124.                    Tandy 1000 HX       280
  125.                    25 MHz 80386       3,400
  126.                    40 MHz 80386       7,100
  127.  
  128.      Fastgraph includes a routine that determines the number of delay units
  129. per clock tick for the processor being used.  This is the fg_measure routine,
  130. which has no arguments and returns the number of delay units per clock tick
  131. as its function value.  Once we determine this value, we can use fg_stall to
  132. delay a program's execution in real time.  This provides a much more refined
  133. delay than the clock tick unit used by fg_waitfor.
  134.  
  135.      Example 16-3 is functionally identical to example 16-1, but it uses the
  136. fg_stall routine instead of fg_waitfor to delay the program execution.  The
  137. program first calls the fg_measure routine to determine number of delay units
  138. equivalent to one clock tick.  It then passes this value to fg_stall, called
  139. 91 times inside the for loop to create the five-second delay (because 91
  140. clock ticks equals five seconds).  The program returns to DOS when you press
  141. any key.
  142.  
  143.                                 Example 16-3.
  144.  
  145.              #include <fastgraf.h>
  146.              #include <stdio.h>
  147.              void main(void);
  148.  
  149.              void main()
  150.              {
  151.                 int i;
  152.                 int units_per_tick;
  153.                 unsigned int seconds;
  154.                 unsigned char key, aux;
  155.  
  156.                 seconds = 0;
  157.  
  158.                 printf("Benchmarking system speed...\n");
  159.                 units_per_tick = fg_measure();
  160.                 printf("Benchmark completed.\n\n");
  161.  
  162.                 do {
  163.                    for (i = 0; i < 91; i++)
  164.                       fg_stall(units_per_tick);
  165.                    seconds += 5;
  166.                    printf("%u seconds have elapsed.\n",seconds);
  167.                    fg_intkey(&key,&aux);
  168.                 }
  169.                 while (key+aux == 0);
  170.              }
  171.  
  172.  
  173.      One final point:  the fg_measure routine takes a few seconds to
  174. benchmark the system speed accurately.  For this reason, you should only call
  175. fg_measure once (typically at the beginning of the program) and use its
  176. return value instead of calling fg_measure throughout the program.
  177.                                             Chapter 16:  Program Timing   302A
  178.  
  179.  
  180. Summary of Timing Routines
  181.  
  182.      This section summarizes the functional descriptions of the Fastgraph
  183. routines presented in this chapter.  More detailed information about these
  184. routines, including their arguments and return values, may be found in the
  185. Fastgraph Reference Manual.
  186.  
  187.      FG_GETCLOCK returns the number of clock ticks since midnight as its
  188. function value.  This quantity is a 32-bit unsigned integer.
  189.  
  190.      FG_MEASURE returns the approximate number of delay units per clock tickas its function value.  This quantity is proportional to the system's
  191. processor speed.
  192.  
  193.      FG_STALL delays a program's execution for a given number of processor-
  194. specific delay units.
  195.  
  196.      FG_WAITFOR delays a program's execution for a given number of clock
  197. ticks.  There are 18.2 clock ticks per second, regardless of the system's
  198. processor speed.